<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <title>jshashset, a JavaScript implementation of HashSet</title>
        <meta name="author" content="Tim Down - tim@timdown.co.uk">
        <meta name="keywords" content="hash, set, JavaScript, hashmap, hashset, hashtable, DHTML">
        <meta name="description" content="jshashtable, a JavaScript hash table implementation">
        <meta name="robots" content="all">
        <link rel="stylesheet" type="text/css" href="main.css" title="Default">
    </head>
    <body>
        <div id="container" class="nonav">
            <div id="header">
                <h1>jshashset 3.0</h1>
                <div id="nav">
                    <span class="navitem">home</span>
                    | <a class="navitem" href="http://code.google.com/p/jshashtable/downloads/list"
                         title="Download">download</a>
                    | <a class="navitem" href="http://www.timdown.co.uk/jshashtable">website</a>
                    | <a class="navitem" href="http://www.timdown.co.uk">timdown.co.uk</a>
                </div>
            </div>
            <div id="content">
                <h1>jshashset 3.0</h1>
                <div id="toc">
                    <h2>Contents</h2>
                    <ul>
                        <li><a href="#intro">Introduction</a></li>
                        <li><a href="#setup">Set-up</a></li>
                        <li><a href="#usage">Usage</a></li>
                        <li><a href="#api">Public API</a></li>
                    </ul>
                </div>
                <div id="intro">
                    <h2>Introduction</h2>
                    <p>
                        <span class="jsh">jshashset</span> is a JavaScript implementation of HashSet, as found in Java
                        or C#'s standard libraries. It depends on <a href="index.html">jshashtable</a> and uses the keys
                        of a <span class="jsh">jshashtable</span> hash table as the underlying set.
                    </p>
                    <p>
                        <span class="jsh">jshashset</span> was first included as a separate download for version 2.1 of
                        <span class="jsh">jshashtable</span> and is included with jshashtable from version 3.0.
                    </p>
                    <p class="linktotop">
                        <a href="#container">Top</a>
                    </p>
                </div>
                <div id="setup">
                    <h2>Set-up</h2>
                    <ol>
                        <li>
                            <h3>Download the code</h3>
                            <p>
                                <strong><a href="http://code.google.com/p/jshashtable/downloads/list"
                                           title="Download">Download jshashset</a></strong>.
                                You can download a compressed or uncompressed version of <code>jshashset.js</code>
                                which are functionally identical or a zip containing compressed and uncompressed code
                                for both <span class="jsh">jshashtable</span> and <span class="jsh">jshashset</span>
                                plus documentation.
                            </p>
                        </li>
                        <li>
                            <h3>Include jshashtable and jshashset in your page</h3>
                            <p>
                                Include <code>jshashtable.js</code> and <code>jshashset.js</code> in that order in
                                script tags in your page. These files create two objects in the global scope, which are
                                <code>Hashtable</code> and <code>HashSet</code>.
                            </p>
                        </li>
                        <li>
                            <h3>Create your hash set</h3>
                            <p>
                                Create your hash set, as in the example below. Any non-null, non-undefined JavaScript
                                object can be used as member of the set.
                            </p>
                    <pre class="code">
&lt;script type="text/javascript" src="jshashtable.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="jshashset.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript"&gt;
    var dinosaurs = new HashSet();

    dinosaurs.add("Triceratops");
    dinosaurs.add("Diplodocus");
    dinosaurs.add("Stegosaurus");

    alert( dinosaurs.values.join(",") );
    /* Triceratops,Diplodocus,Stegosaurus */
&lt;/script&gt;
</pre>
                        </li>
                    </ol>
                    <p class="linktotop">
                        <a href="#container">Top</a>
                    </p>
                </div>
                <div id="api">
                    <h2>Public API</h2>
                    <h4>Constructors</h4>
                    <ul class="propertieslist">
                        <li class="method">
                            <div class="methodsignature">
                                <code><strong>HashSet</strong>()</code>
                            </div>
                            <p>
                                Creates a new, empty hash set.
                            </p>
                        </li>
                        <li class="method">
                            <div class="methodsignature">
                                <code><strong>HashSet</strong>(Object <em>options</em>)</code>
                            </div>
                            <div class="summary">
                                <p class="new">New in version 3.0</p>
                                <p>
                                    Creates a new, empty hash set with the supplied options.
                                </p>
                            </div>
                            <div class="paramsheading">Option properties:</div>
                            <ul class="params">
                                <li class="param">
                                    <code class="paramname">hashCode</code>
                                    <div>
                                        A function that provides hash codes for objects placed in the set. It is passed
                                        the object to be hashed as its only parameter. If not provided, the set checks
                                        whether the object has a <code>hashCode()</code> method, and if not, calls
                                        <code>toString()</code> on the object.
                                    </div>
                                </li>
                                <li class="param">
                                    <code class="paramname">equals</code>
                                    <div>
                                        <p>
                                            A function that checks for equality between two objects with the same hash
                                            code. If two objects that are considered equal then only one can be in the
                                            set at any one time.
                                        </p>
                                        <p>
                                            This function is passed the two objects to be compared as its parameters. If
                                            not provided, the set checks whether either object being compared has an
                                            <code>equals()</code> method, and if not, compares the objects using the
                                            <code>===</code> operator.
                                        </p>
                                    </div>
                                </li>
                                <li class="param">
                                    <code class="paramname">replaceDuplicateKey</code>
                                    <p class="new">New in version 3.0</p>
                                    <p>
                                        Controls what happens when <code>add()</code> is called with an object that is
                                        equal to an existing object in the set. If <code>replaceDuplicateKey</code> is
                                        <code>true</code>, the existing key is always replaced by the new key.
                                        Otherwise, the existing key is left in place (which is what always happened
                                        prior to version 3.0). The default is <code>true</code>; prior to version 3.0.
                                    </p>
                                </li>
                            </ul>
                        </li>
                        <li class="method">
                            <div class="methodsignature">
                                <code><strong>HashSet</strong>(Function <em>hashingFunction</em>, Function
                                    <em>equalityFunction</em>)</code>
                            </div>
                            <p class="summary">
                                Creates a new, empty hash set with the supplied hashing function and equality
                                function. This form maintains backwards compatibility with versions prior to 3.0.
                                The following line
                            </p>
                            <pre class="code">
var set = new HashSet(hashingFunction, equalityFunction);
</pre>
                            <p>... is equivalent to</p>
                            <pre class="code">
var set = new HashSet( { hashCode: hashingFunction, equals: equalityFunction } );
</pre>
                            <div class="paramsheading">Parameters:</div>
                            <ul class="params">
                                <li class="param">
                                    <code class="paramname">hashingFunction</code>
                                    <p>See above.</p>
                                </li>
                                <li class="param">
                                    <code class="paramname">equalityFunction</code>
                                    <p>See above.</p>
                                </li>
                            </ul>
                        </li>
                    </ul>
                    <h4>Methods</h4>
                    <ul class="propertieslist">
                        <li class="method" id="put">
                            <div class="methodsignature"><code>void <strong>add</strong>(mixed
                                <em>value</em>)</code></div>
                            <div class="summary">
                                Adds the specified object or primitive to the set. <code>value</code> replaces any
                                member of the set equal to it, unless <code>replaceDuplicateKey</code> was set to
                                <code>false</code> in the constructor.
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>void <strong>addAll</strong>(Array
                                <em>arr</em>)</code></div>
                            <div class="summary">
                                Adds all members of an array <code>arr</code> to the set in order. Each member of
                                <code>arr</code> replaces any member of the set equal to it, unless
                                <code>replaceDuplicateKey</code> was set to <code>false</code> in the constructor, in
                                which case the original value is left in place.
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>Array <strong>values</strong>()</code></div>
                            <div class="summary">
                                <p>
                                    Returns an array containing all the members of the set in unspecified order.
                                </p>
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>void <strong>remove</strong>(mixed
                                <em>key</em>)</code></div>
                            <div class="summary">
                                <p>
                                    Removes the specified value from the set.
                                </p>
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>Boolean <strong>contains</strong>(mixed
                                <em>value</em>)</code></div>
                            <div class="summary">
                                <p>
                                    Returns whether the set contains the specified value.
                                </p>
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>void <strong>clear</strong>()</code></div>
                            <div class="summary">
                                <p>
                                    Removes all members from the set.
                                </p>
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>Number <strong>size</strong>()</code></div>
                            <div class="summary">
                                <p>
                                    Returns the number of members contained in the set.
                                </p>
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>Boolean <strong>isEmpty</strong>()</code></div>
                            <div class="summary">
                                <p>
                                    Returns <code>true</code> if the set contains no members, <code>false</code>
                                    otherwise.
                                </p>
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>Boolean <strong>isSubsetOf</strong>(HashSet
                                <em>set</em>)</code></div>
                            <div class="summary">
                                <p>
                                    Returns <code>true</code> if every member this set is also a member of
                                    <code>set</code>, <code>false</code> otherwise.
                                </p>
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>HashSet <strong>clone</strong>()</code></div>
                            <div class="summary">
                                <p>
                                    Creates and returns a shallow copy of the set, using the same options provided to
                                    the set when it was constructed.
                                </p>
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>HashSet <strong>intersection</strong>(HashSet
                                <em>set</em>)</code></div>
                            <div class="summary">
                                <p>
                                    Creates and returns a new <code>HashSet</code> containing only those elements that
                                    are contained in both this set and <code>set</code>.
                                </p>
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>HashSet <strong>union</strong>(HashSet
                                <em>set</em>)</code></div>
                            <div class="summary">
                                <p>
                                    Creates and returns a new <code>HashSet</code> containing those elements that are
                                    contained either of or both this set and <code>set</code>.
                                </p>
                            </div>
                        </li>
                        <li class="method">
                            <div class="methodsignature"><code>HashSet <strong>complement</strong>(HashSet
                                <em>set</em>)</code></div>
                            <div class="summary">
                                <p>
                                    Creates and returns a new <code>HashSet</code> containing those elements that are
                                    contained in this set but not <code>set</code>.
                                </p>
                            </div>
                        </li>
                    </ul>
                    <p class="linktotop">
                        <a href="#container">Top</a>
                    </p>
                </div>
            </div>
            <div id="footer">
                Written by Tim Down. <a href="mailto:tim@timdown.co.uk">tim@timdown.co.uk</a>
                <br>
                <span class="jsh">jshashtable</span> is distributed under the
                <a href="http://www.apache.org/licenses/LICENSE-2.0.html" title="Apache License, Version 2.0">Apache
                    License, Version 2.0</a>
            </div>
        </div>
    </body>
</html>
